#!/usr/bin/env python
# -*- conding:utf-8 -*-
# argparse --- 命令行选项、参数和子命令解析器
# https://docs.python.org/zh-cn/3/library/argparse.html#parsing-arguments

import argparse
if __name__ == "__main__":
    # 创建一个解析器：使用 argparse 的第一步是创建一个 ArgumentParser 对象：ArgumentParser 对象包含将命令行解析成 Python 数据类型所需的全部信息。
    parser = argparse.ArgumentParser(description='Process some integers.')
    # 添加参数：给一个 ArgumentParser 添加程序参数信息是通过调用 add_argument() 方法完成的。通常，这些调用指定 ArgumentParser 如何获取命令行字符串并将其转换为对象。这些信息在 parse_args() 调用时被存储和使用。
    parser.add_argument('integers', metavar='N', type=int,
                        nargs='+', help='an integer for the accumulator')
    parser.add_argument('--sum', dest='accumulate', action='store_const',
                        const=sum, default=max, help='sum the integers(default:find the max)')
    # 然后，调用 parse_args() 将返回一个具有 integers 和 accumulate 两个属性的对象。integers 属性将是一个包含一个或多个整数的列表，而 accumulate 属性当命令行中指定了 --sum 参数时将是 sum() 函数，否则则是 max() 函数。
    # 解析参数：ArgumentParser 通过 parse_args() 方法解析参数。它将检查命令行，把每个参数转换为适当的类型然后调用相应的操作。在大多数情况下，这意味着一个简单的 Namespace 对象将从命令行解析出的属性构建：
    # print(parser.parse_args(['--sum', '7', '-1', '42']))
    # 在脚本中，通常 parse_args() 会被不带参数调用，而 ArgumentParser 将自动从 sys.argv 中确定命令行参数。

    # ArgumentParser 对象：创建一个新的 ArgumentParser 对象。所有的参数都应当作为关键字参数传入。每个参数在下面都有它更详细的描述：
    # prog - 程序的名称（默认值：sys.argv[0]）
    # usage - 描述程序用途的字符串（默认值：从添加到解析器的参数生成）
    # description - 在参数帮助文档之前显示的文本（默认值：无）
    # epilog - 在参数帮助文档之后显示的文本（默认值：无）
    # parents - 一个 ArgumentParser 对象的列表，它们的参数也应包含在内
    # formatter_class - 用于自定义帮助文档输出格式的类
    # prefix_chars - 可选参数的前缀字符集合（默认值： '-'）
    # fromfile_prefix_chars - 当需要从文件中读取其他参数时，用于标识文件名的前缀字符集合（默认值： None）
    # argument_default - 参数的全局默认值（默认值： None）
    # conflict_handler - 解决冲突选项的策略（通常是不必要的）
    # add_help - 为解析器添加一个 - h/--help 选项（默认值： True）
    # allow_abbrev - 如果缩写是无歧义的，则允许缩写长选项 （默认值：True）
    # exit_on_error - 决定当错误发生时是否让 ArgumentParser 附带错误信息退出。 (默认值: True)

    # add_argument() 方法
    # ArgumentParser.add_argument(name or flags...[, action][, nargs][, const][, default][, type][, choices][, required][, help][, metavar][, dest])
    # 定义单个的命令行参数应当如何解析。每个形参都在下面有它自己更多的描述，长话短说有：
    # name or flags - 一个命名或者一个选项字符串的列表，例如 foo 或 - f, --foo。
    # action - 当参数在命令行中出现时使用的动作基本类型。
    # nargs - 命令行参数应当消耗的数目。
    # const - 被一些 action 和 nargs 选择所需求的常数。
    # default - 当参数未在命令行中出现并且也不存在于命名空间对象时所产生的值。
    # type - 命令行参数应当被转换成的类型。
    # choices - 可用的参数的容器。
    # required - 此命令行选项是否可省略 （仅选项可用）。
    # help - 一个此选项作用的简单描述。
    # metavar - 在使用方法消息中使用的参数值示例。
    # dest - 被添加到 parse_args() 所返回对象上的属性名。

    # 子命令
    # ArgumentParser.add_subparsers([title][, description][, prog][, parser_class][, action][, option_string][, dest][, required][, help][, metavar])
    # 许多程序都会将其功能拆分为一系列子命令，例如，svn 程序包含的子命令有 svn checkout, svn update 和 svn commit。 当一个程序能执行需要多组不同种类命令行参数时这种拆分功能的方式是一个非常好的主意。 ArgumentParser 通过 add_subparsers() 方法支持创建这样的子命令。 add_subparsers() 方法通常不带参数地调用并返回一个特殊的动作对象。 这种对象只有一个方法 add_parser()，它接受一个命令名称和任意多个 ArgumentParser 构造器参数，并返回一个可以通常方式进行修改的 ArgumentParser 对象。
    # 形参的描述
    # title - 输出帮助的子解析器分组的标题；如果提供了描述则默认为 "subcommands"，否则使用位置参数的标题
    # description - 输出帮助中对子解析器的描述，默认为 None
    # prog - 将与子命令帮助一同显示的用法信息，默认为程序名称和子解析器参数之前的任何位置参数。
    # parser_class - 将被用于创建子解析器实例的类，默认为当前解析器类（例如 ArgumentParser）
    # action - 当此参数在命令行中出现时要执行动作的基本类型
    # dest - 将被用于保存子命令名称的属性名；默认为 None 即不保存任何值
    # required - 是否必须要提供子命令，默认为 False
    # help - 在输出帮助中的子解析器分组帮助信息，默认为 None
    # metavar - 帮助信息中表示可用子命令的字符串；默认为 None 并以 {cmd1, cmd2, ..} 的形式表示子命令

    # 示例：
    parser = argparse.ArgumentParser(description='Process some integers.')
    parser.add_argument('integers', metavar='N', type=int, nargs='+',
                        help='an integer for the accumulator')
    parser.add_argument('--sum', dest='accumulate', action='store_const',
                        const=sum, default=max,
                        help='sum the integers (default: find the max)')
    args = parser.parse_args()
    print(args.accumulate(args.integers))
